import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './NotificationToast.stories';

<Meta of={Stories} />

# NotificationToast

<Status variant="stable" />

The `NotificationToast` component provides quick status messages to the user. A toast can follow a user action (e.g. submitting a form) or it can appear without having been triggered explicitly (e.g. a toast message "You made a new sale" showing real-time sales in an app).

<Story of={Stories.Base} />
<Props />

## Component variations

### Toast variants

<Story of={Stories.Variants} />

- Use the 'info' variant for informational, neutral messages.
- Use the 'success' variant the successful messages.
- Use the 'warning' variant for warning messages, and other information a user should be aware of.
- Use the 'danger' variant for error messages.

### Toast with headline

<Story of={Stories.WithHeadline} />

## Usage in code

First, wrap your application in the `ToastProvider` which keeps track of the open toasts and ensures accessibility of the toast messages.

```tsx
// _app.tsx for Next.js or App.js for CRA
import { ToastProvider } from '@sumup-oss/circuit-ui';

export default function App() {
  return <ToastProvider>{/* Your content goes here... */}</ToastProvider>;
}
```

Then, use the `useNotificationToast` hook to open a toast from a component:

```tsx
import { useNotificationToast, Button } from '@sumup-oss/circuit-ui';

export function App({}) {
  const { setToast } = useNotificationToast();

  const handleClick = () => {
    setToast({
      variant: 'success',
      body: 'This is a toast message',
    });
  };

  return <Button onClick={handleClick}>Open toast</Button>;
}
```

### Custom positioning

Change the position of notifications by passing the `position` prop. Supported values are `bottom` (default), `top` and `top-right`:

<Story of={Stories.Position} />

## Accessibility

By their nature as status messages, toasts are rendered inside a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) using `role="status"` and `aria-live="polite"`.

A live region must always exist in the DOM _before_ content gets added to it, to ensure that additions are properly announced. In Circuit UI, this is handled by the `ToastProvider`.

### Best practices

#### Toasts shouldn't have interactive content

Toast messages should not contain any interactive elements. Screen readers will announce raw text within the toast as it appears, without structure and without moving focus to the toast element.

For example, if a toast reads “You successfully updated your data" followed by an "Undo" button, screen readers will announce "You successfully updated your data. Undo", but wouldn't allow keyboard users to interact with the button because it will never receive focus.

If you need a notification with an action button, use the [`NotificationInline`](Notifications/NotificationInline) component instead.

#### Toasts should be visible for at least 6 seconds

The auto-dismiss duration of the toast is adjustable.

Based on how fast the [average American reads](https://sheribyrnehaber.medium.com/designing-toast-messages-for-accessibility-fb610ac364be), a good length of time to keep the toast message up is 5 seconds plus 1 extra second for every 120 words.

The `NotificationToast` default and minimum auto-dismiss duration is therefore 6 seconds. Adapt it based on the length of your content.

### Resources

#### Related articles

- [Notifications](https://inclusive-components.design/notifications/) by Heydon Pickering in Inclusive Components
- [Defining toast messages](https://adrianroselli.com/2020/01/defining-toast-messages.html) by Adrian Roselli

#### Related WCAG success criteria

- 4.1.3: [Status messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html)
